import {Layout} from '../../src/Layout';
export default Layout;

import docs from 'docs:react-aria-components';
import vanillaDocs from 'docs:vanilla-starter/CheckboxGroup';
import '../../tailwind/tailwind.css';
import Anatomy from '@react-aria/checkbox/docs/checkboxgroup-anatomy.svg';
import {InlineAlert, Heading, Content} from '@react-spectrum/s2'

export const tags = ['input'];
export const relatedPages = [
  {title: 'useCheckboxGroup', url: 'CheckboxGroup/useCheckboxGroup.html'},
  {title: 'Testing CheckboxGroup', url: './CheckboxGroup/testing'}
];
export const description = 'Allows a user to select multiple items from a list of options.';

# CheckboxGroup

<PageDescription>{docs.exports.CheckboxGroup.description}</PageDescription>

<ExampleSwitcher>
  ```tsx render docs={vanillaDocs.exports.CheckboxGroup} links={vanillaDocs.links} props={['label', 'description', 'isDisabled']} initialProps={{label: 'Favorite sports'}} type="vanilla" files={["starters/docs/src/CheckboxGroup.tsx", "starters/docs/src/CheckboxGroup.css"]}
  "use client";
  import {CheckboxGroup} from 'vanilla-starter/CheckboxGroup';
  import {Checkbox} from 'vanilla-starter/Checkbox';

  <CheckboxGroup/* PROPS */>
    <Checkbox value="soccer">Soccer</Checkbox>
    <Checkbox value="baseball">Baseball</Checkbox>
    <Checkbox value="basketball">Basketball</Checkbox>
  </CheckboxGroup>
  ```

  ```tsx render docs={vanillaDocs.exports.CheckboxGroup} links={vanillaDocs.links} props={['label', 'description', 'isDisabled']} initialProps={{label: 'Favorite sports'}} type="tailwind" files={["starters/tailwind/src/Checkbox.tsx"]}
  "use client";
  import {CheckboxGroup, Checkbox} from 'tailwind-starter/Checkbox';

  <CheckboxGroup/* PROPS */>
    <Checkbox value="soccer">Soccer</Checkbox>
    <Checkbox value="baseball">Baseball</Checkbox>
    <Checkbox value="basketball">Basketball</Checkbox>
  </CheckboxGroup>
  ```
</ExampleSwitcher>

## Value

Use the `value` or `defaultValue` prop to set the selected items, and `onChange` to handle selection changes.

```tsx render
"use client";
import {CheckboxGroup} from 'vanilla-starter/CheckboxGroup';
import {Checkbox} from 'vanilla-starter/Checkbox';
import {useState} from 'react';

function Example() {
  let [selected, setSelected] = useState(['soccer', 'baseball']);

  return (
    <>
      <CheckboxGroup
        label="Favorite sports"
        /*- begin highlight -*/
        value={selected}
        onChange={setSelected}>
        {/*- end highlight -*/}
        <Checkbox value="soccer">Soccer</Checkbox>
        <Checkbox value="baseball">Baseball</Checkbox>
        <Checkbox value="basketball">Basketball</Checkbox>
      </CheckboxGroup>
      <p>Current selection: {selected.join(', ')}</p>
    </>
  );
}
```

## Forms

Use the `name` prop to submit the selected checkboxes to the server. Set the `isRequired` prop on the `<CheckboxGroup>` to validate the user selects at least one checkbox, or on individual checkboxes. See the [Forms](forms) guide to learn more.

```tsx render
"use client";
import {CheckboxGroup} from 'vanilla-starter/CheckboxGroup';
import {Checkbox} from 'vanilla-starter/Checkbox';
import {Button} from 'vanilla-starter/Button';
import {Form} from 'vanilla-starter/Form';;

<Form>
  <div style={{display: 'flex', gap: 32, flexWrap: 'wrap'}}>
    <CheckboxGroup
      label="Sandwich condiments"
      /*- begin highlight -*/
      name="condiments"
      isRequired>
      {/*- end highlight -*/}
      <Checkbox value="lettuce">Lettuce</Checkbox>
      <Checkbox value="tomato">Tomato</Checkbox>
      <Checkbox value="onion">Onion</Checkbox>
      <Checkbox value="sprouts">Sprouts</Checkbox>
    </CheckboxGroup>
    <CheckboxGroup label="Agree to the following" name="terms">
      {/*- begin highlight -*/}
      <Checkbox value="terms" isRequired>Terms and conditions</Checkbox>
      <Checkbox value="privacy" isRequired>Privacy policy</Checkbox>
      <Checkbox value="cookies" isRequired>Cookie policy</Checkbox>
      {/*- end highlight -*/}
    </CheckboxGroup>
  </div>
  <Button type="submit" style={{marginTop: 8}}>Submit</Button>
</Form>
```

## API

<Anatomy />

```tsx links={{CheckboxGroup: '#checkboxgroup', Checkbox: 'Checkbox'}}
<CheckboxGroup>
  <Label />
  <Checkbox />
  <Text slot="description" />
  <FieldError />
</CheckboxGroup>
```

### CheckboxGroup

<PropTable component={docs.exports.CheckboxGroup} links={docs.links} />
